Motivation and Context

Issue:

• Tools can hint that they are idempotent via setting the idempotencyHint to true
• No standard way to provide an idempotency key to a tool that hints they are idempotent
• We want to be able to retry tool calls upon non-logical timeouts, like a timeout, with the same idempotency key

Solution:

• Introduce a new idempotencyKey attribute to the CallToolRequestParams DTO that is populated when calling a tool
• If the client wishes to, they can set max_timeout_retries to a value greater than 0, which triggers tool retry on timeout with the same idempotency key

How Has This Been Tested?

Unit tests and demo code (temporarily committed)

Breaking Changes

Not breaking, by default, retry is not enabled (hence not breaking existing behaviour)

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

WIP

Additional context

This is a rough implementation of what an idempotencyKey attribute could look like in the spec. This is not a PR ready to be merged, but just to demo what it could look like, to "add some color to the picture". This is part of an ongoing discussion in the #financial-services-wg to support idempotent tools.

• Original "scrap doc" on issue
• Example repo demonstrating problem
• Video summary of the above